home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kio / kdesasl.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  5.6 KB  |  170 lines
  1. /* This file is part of the KDE libraries
  2.    Copyright (C) 2001-2002 Michael HΣckel <haeckel@kde.org>
  3.    $Id: kdesasl.h 465272 2005-09-29 09:47:40Z mueller $
  4.  
  5.    This library is free software; you can redistribute it and/or
  6.    modify it under the terms of the GNU Library General Public
  7.    License version 2 as published by the Free Software Foundation.
  8.  
  9.    This library is distributed in the hope that it will be useful,
  10.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.    Library General Public License for more details.
  13.  
  14.    You should have received a copy of the GNU Library General Public License
  15.    along with this library; see the file COPYING.LIB.  If not, write to
  16.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17.    Boston, MA 02110-1301, USA.
  18. */
  19.  
  20. #ifndef KDESASL_H
  21. #define KDESASL_H
  22.  
  23. #include <qstring.h>
  24.  
  25. #include <kdelibs_export.h>
  26.  
  27. class KURL;
  28. class QStrIList;
  29.  
  30. /**
  31.  * This library can create responses for SASL authentication for a given
  32.  * challenge and a given secret. This way of authentication is common for
  33.  * SMTP, POP3, IMAP and LDAP.
  34.  *
  35.  * SASL is one way strong encryption and therefore useful for authentication,
  36.  * but not for secret information transfer.
  37.  * It is possibly to prove with SASL to know a shared secret like a password.
  38.  * It is not possible with SASL to transfer any other information in an
  39.  * encrypted way. For that purpose OpenPGP or SSL are useful.
  40.  *
  41.  * Currently PLAIN (RFC 2595), LOGIN (not really a SASL mechanism, but
  42.  * used like that in IMAP and SMTP), CRAM-MD5 (RFC 2195) and
  43.  * DIGEST-MD5 (RFC 2831) authentication are supported.  PLAIN and
  44.  * LOGIN transmit the credentials in the clear (apart from a possible
  45.  * base64 encoding).
  46.  *
  47.  * For KDE 3.2, the API has been extended to allow transparent use of
  48.  * all currently supported SASL mechanisms. Example:
  49.  * \code
  50.  * KDESasl sasl( myUser, myPass, myProtocol );
  51.  * if ( !sasl.chooseMethod( myMechanismsSupportedByServer ) )
  52.  *   return false; // couldn't agree on a method
  53.  *
  54.  * int numResponses = 0;
  55.  * if ( sasl.clientStarts() ) { // check whether we're supposed to start the dialog
  56.  *   ++numResponses;
  57.  *   mySendAuthCommand( sasl.method(), sasl.getResponse() );
  58.  * } else {
  59.  *   mySendAuthCommand( sasl.method() );
  60.  * }
  61.  * for ( ; !sasl.dialogComplete( numResponses ) ; ++numResponses ) {
  62.  *   QByteArray challenge = myRecvChallenge();
  63.  *   mySendResponse( sasl.getResponse( challenge ) );
  64.  * }
  65.  * return myCheckSuccess();
  66.  * \endcode
  67.  *
  68.  * @author Michael HΣckel <haeckel@kde.org>
  69.  * @version $Id: kdesasl.h 465272 2005-09-29 09:47:40Z mueller $
  70.  */
  71.  
  72. class KIO_EXPORT KDESasl
  73. {
  74.  
  75. public:
  76.   /**
  77.    * Construct a sasl object and initialize it with the username and password
  78.    * passed via the url.
  79.    */
  80.   KDESasl(const KURL &aUrl);
  81.   /**
  82.    * This is a conveniece function and differs from the above function only by
  83.    * what arguments it accepts.
  84.    */
  85.   KDESasl(const QString &aUser, const QString &aPass, const QString &aProtocol);
  86.   /*
  87.    * You need to have a virtual destructor!
  88.    */
  89.   virtual ~KDESasl();
  90.   /**
  91.    * @returns the most secure method from the given methods and use it for
  92.    * further operations.
  93.    */
  94.   virtual QCString chooseMethod(const QStrIList aMethods);
  95.   /**
  96.    * Explicitely set the SASL method used.
  97.    */
  98.   virtual void setMethod(const QCString &aMethod);
  99.   /**
  100.    * @return the SASL method used.
  101.    * @since 3.2
  102.    */
  103.   QCString method() const;
  104.   /**
  105.    * @param numCalls number of times getResponse() has been called.
  106.    * @return whether the challenge/response dialog has completed
  107.    *
  108.    * @since 3.2
  109.    */
  110.   bool dialogComplete( int numCalls ) const;
  111.   /**
  112.    * @return whether the currently selected mechanism results in
  113.    * cleartext passwords being sent over the network and thus should
  114.    * be used only under TLS/SSL cover or for legacy servers.
  115.    *
  116.    * @since 3.2
  117.    */
  118.   bool isClearTextMethod() const;
  119.   /**
  120.    * Creates a response using the formerly chosen SASL method.
  121.    * For LOGIN authentication you have to call this function twice. KDESasl
  122.    * realizes on its own, if you are calling it for the first or for the
  123.    * second time.
  124.    * @param aChallenge is the challenge sent to create a response for
  125.    * @param aBase64 specifies, whether the authentication protocol uses base64
  126.    * encoding. The challenge is decoded from base64 and the response is
  127.    * encoded base64 if set to true.
  128.    */
  129.    QCString getResponse(const QByteArray &aChallenge=QByteArray(), bool aBase64 = true);
  130.   /**
  131.    * Create a response as above but place it in a QByteArray
  132.    */
  133.   QByteArray getBinaryResponse(const QByteArray &aChallenge=QByteArray(), bool aBase64=true); 
  134.   /**
  135.    * Returns true if the client is supposed to initiate the
  136.    * challenge-respinse dialog with an initial response (which most
  137.    * protocols can transfer alongside the authentication command as an
  138.    * optional second parameter). This method relieves the sasl user
  139.    * from knowing details about the mechanism. If true, use 
  140.    * #getResponse() with a null challenge.
  141.    *
  142.    * @since 3.2
  143.    */
  144.   bool clientStarts() const;
  145. protected:
  146.   /**
  147.    * PLAIN authentication as described in RFC 2595
  148.    */
  149.   virtual QByteArray getPlainResponse();
  150.   /**
  151.    * LOGIN authentication
  152.    */
  153.   virtual QByteArray getLoginResponse();
  154.   /**
  155.    * CRAM-MD5 authentication as described in RFC 2195
  156.    */
  157.   virtual QByteArray getCramMd5Response(const QByteArray &aChallenge);
  158.   /**
  159.    * DIGEST-MD5 authentication as described in RFC 2831
  160.    */
  161.   virtual QByteArray getDigestMd5Response(const QByteArray &aChallenge);
  162.  
  163. private:
  164.   QString mProtocol, mUser, mPass;
  165.   QCString mMethod;
  166.   bool mFirst;
  167. };
  168.  
  169. #endif
  170.